Expand description
Autocxx
This project is a tool for calling C++ from Rust in a heavily automated, but safe, fashion.
The intention is that it has all the fluent safety from cxx whilst generating interfaces automatically from existing C++ headers using a variant of bindgen. Think of autocxx as glue which plugs bindgen into cxx.
For full documentation, see the manual.
Overview
autocxx::include_cpp! {
#include "url/origin.h"
generate!("url::Origin")
safety!(unsafe_ffi)
}
fn main() {
let o = ffi::url::Origin::CreateFromNormalizedTuple("https",
"google.com", 443);
let uri = o.Serialize();
println!("URI is {}", uri.to_str().unwrap());
}License and usage notes
This is not an officially supported Google product.
Licensed under either of Apache License, Version 2.0 or MIT license at your option.Re-exports
Modules
Tools to export Rust code to C++.
Imports which you’re likely to want to use.
Module to make Rust subclasses of C++ classes. See CppSubclass
for details.
Macros
Entirely block some type from appearing in the generated code. This can be useful if there is a type which is not understood by bindgen or autocxx, and incorrect code is otherwise generated. This is ‘greedy’ in the sense that any functions/methods which take or return such a type will also be blocked.
Avoid generating implicit constructors for this type. The rules for when to generate C++ implicit constructors are complex, and if autocxx gets it wrong, you can block such constructors using this.
A concrete type to make, for example
concrete!("Container<Contents>").
All types msut already be on the allowlist by having used
generate! or similar.
Whether to avoid generating cxx::UniquePtr and cxx::Vector
implementations. This is primarily useful for reducing test cases and
shouldn’t be used in normal operation.
Skip the normal generation of a make_string function
and other utilities which we might generate normally.
A directive to be included inside
include_cpp - see include_cpp for general information.
Indicates that a C++ type is not to be generated by autocxx in this case,
but instead should refer to some pre-existing Rust type. Unlike
extern_cpp_type!, there’s no need for the size and alignment of this
type to be correct.
Indicates that a C++ type is not to be generated by autocxx in this case,
but instead should refer to some pre-existing Rust type.
Note that the size and alignment of this type must be correct.
If you wish for the type to be POD, you can use a pod! directive too.
Generate Rust bindings for the given C++ type or function. A directive to be included inside include_cpp - see include_cpp for general information. See also generate_pod.
Generate Rust bindings for all C++ types and functions found. Highly experimental and not recommended. A directive to be included inside include_cpp - see include_cpp for general information. See also generate.
Generate Rust bindings for all C++ types and functions in a given namespace. A directive to be included inside include_cpp - see include_cpp for general information. See also generate.
Generate as “plain old data” and add to allowlist. Generate Rust bindings for the given C++ type such that it can be passed and owned by value in Rust. This only works for C++ types which have trivial move constructors and no destructor - you’ll encounter a compile error otherwise. If your type doesn’t match that description, use generate instead, and own the type using UniquePtr. A directive to be included inside include_cpp - see include_cpp for general information.
Include a C++ header. A directive to be included inside include_cpp - see include_cpp for details
Include some C++ headers in your Rust project.
Indicates that a C++ type can definitely be instantiated. This has effect only in a very specific case:
The name of the mod to be generated with the FFI code.
The default is ffi.
Generate as “plain old data”. For use with generate_all and similarly experimental.
Deprecated - use extern_rust_type instead.
Specifies a global safety policy for functions generated
from these headers. By default (without such a safety!
directive) all such functions are marked as unsafe and
therefore can only be called within an unsafe {} block
or some unsafe function which you create.
Structs
autocxx couldn’t generate these bindings. If you come across a method, type or function which refers to this type, it indicates that autocxx couldn’t generate that binding. A documentation comment should be attached indicating the reason.
A C++ char16_t
Newtype wrapper for an int
Newtype wrapper for a long
Newtype wrapper for a long long
Newtype wrapper for an short
Newtype wrapper for an unsigned char
Newtype wrapper for an unsigned int
Newtype wrapper for an unsigned long
Newtype wrapper for an unsigned long long
Newtype wrapper for an unsigned short
Newtype wrapper for a C void. Only useful as a *c_void
Traits
A C++ non-const reference. These are different from Rust’s &mut T in that
several C++ references can exist to the same underlying data (“aliasing”)
and that’s not permitted in Rust.
Any newtype wrapper which causes the contained object to obey C++ reference semantics rather than Rust reference semantics.
A C++ const reference. These are different from Rust’s &T in that
these may exist even while the object is mutated elsewhere.
Equivalent to std::convert::AsMut, but returns a pinned mutable reference
such that cxx methods can be called on it.
A trait representing a parameter to a C++ function which is received by rvalue (i.e. by move).
A trait representing a parameter to a C++ function which is received by value.
Provides utility functions to emplace any moveit::New into a
Box. Automatically imported by the autocxx prelude
and implemented by any (autocxx-related) moveit::New.
Emulates the WithinBox trait, but for trivial (plain old data) types.
This allows such types to behave identically if a type is changed from
generate! to generate_pod!.
Provides utility functions to emplace any moveit::New into a
cxx::UniquePtr. Automatically imported by the autocxx prelude
and implemented by any (autocxx-related) moveit::New.
Emulates the WithinUniquePtr trait, but for trivial (plain old data) types.
This allows such types to behave identically if a type is changed from
generate! to generate_pod!.
Functions
Explicitly force a value parameter to be taken by copy.
Explicitly force a value parameter to be taken usign C++ move semantics.
Explicitly force a value parameter to be taken using any type of crate::moveit::new::New,
i.e. a constructor.